---
id: http-api
sidebar_label: HTTP API
title: Rasa Open Source HTTP API
description: Read about Rasa's HTTP API that has endpoints for conversations, training models, and configuring your bot.
abstract: You can use the HTTP API to interact with a running Rasa Open Source server. With the API, you can train models,
  send messages, run tests, and more.
---

:::tip Looking for API endpoints? 
Check out the [API Spec](/pages/http-api) for all of the available endpoints as well as their request and response formats.

:::

## Enabling the HTTP API

By default, running a Rasa server does not enable the API endpoints. Interactions
with the bot can happen over the exposed `webhooks/<channel>/webhook` endpoints.

To enable the API for direct interaction with conversation trackers and other
bot endpoints, add the `--enable-api` parameter to your run command:

```bash
rasa run --enable-api
```

Note that you start the server with an NLU-only model, not all the available endpoints
can be called. Some endpoints will return a 409 status code, as a trained
dialogue model is needed to process the request.


:::caution
Make sure to secure your server, either by restricting access to the server (e.g. using firewalls), or
by enabling an authentication method. See [Security Considerations](./http-api.mdx#security-considerations).

:::

By default, the HTTP server runs as a single process. You can change the number
of worker processes using the `SANIC_WORKERS` environment variable. It is
recommended that you set the number of workers to the number of available CPU cores
(check out the
[Sanic docs](https://sanicframework.org/en/guide/deployment/running.html#workers)
for more details). This will only work in combination with the
`RedisLockStore` (see [Lock Stores](./lock-stores.mdx).

:::caution
The [SocketIO channel](./connectors/your-own-website.mdx#websocket-channel) does not support multiple worker processes. 

:::

## Security Considerations

We recommend to not expose the Rasa Server to the outside world, but
rather connect to it from your backend over a private connection (e.g.
between docker containers).

Nevertheless, there are two authentication methods built in:

### Token Based Auth

Pass in the token using `--auth-token thisismysecret` when starting
the server:

```bash
rasa run \
    -m models \
    --enable-api \
    --log-file out.log \
    --auth-token thisismysecret
```

Your requests should pass the token, in our case `thisismysecret`,
as a parameter:

```bash
curl -XGET localhost:5005/conversations/default/tracker?token=thisismysecret
```

### JWT Based Auth

Enable JWT based authentication using `--jwt-secret thisismysecret`.
Requests to the server need to contain a valid JWT token in
the `Authorization` header that is signed using this secret
and the `HS256` algorithm.

The token's payload must contain an object under the `user` key,
which in turn must contain the `username` and `role` attributes.
If the `role` is `admin`, all endpoints are accessible.
If the `role` is `user`, endpoints with a `sender_id` parameter are only accessible
if the `sender_id` matches the payload's `username` property.

```bash
rasa run \
    -m models \
    --enable-api \
    --log-file out.log \
    --jwt-secret thisismysecret
```

Your requests should have set a proper JWT header:

```text
"Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ"
                 "zdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIi"
                 "wiaWF0IjoxNTE2MjM5MDIyfQ.qdrr2_a7Sd80gmCWjnDomO"
                 "Gl8eZFVfKXA6jhncgRn-I"
```

The following is an example payload for a JWT token:

```json
{
    "user": {
        "username": "<sender_id>",
        "role": "user"
    }
}
```

To create and encode the token, you can use tools such as the [JWT Debugger](https://jwt.io/), or a Python module such as [PyJWT](https://pyjwt.readthedocs.io/en/latest/).

